Lấy lịch sử tỷ giá
Tra cứu lịch sử tỷ giá theo ngày của một đồng ngoại tệ so với VND. Mỗi ngày trả về tỷ giá chốt cuối ngày (closing rate) cho cả hai chiều Sell/Buy, phục vụ đối chiếu và phân tích.
Luồng xử lý
Đường dẫn
- URL:
/api/v1/fx/historical-rate - Method:
POST
Request
| Tham số | Loại dữ liệu | Bắt buộc | Mô tả |
|---|---|---|---|
| request_id | string(50) | Có | Xem mục 3 Giới thiệu |
| request_time | string(19) | Có | Xem mục 3 Giới thiệu |
| merchant_code | string(20) | Có | Xem mục 3 Giới thiệu |
| currency | string(3) | Có | Đồng ngoại tệ cần tra cứu (đối ứng luôn là VND), ví dụ USD |
| from_date | string(10) | Có | Ngày bắt đầu (bao gồm), định dạng YYYY-MM-DD |
| to_date | string(10) | Có | Ngày kết thúc (bao gồm), định dạng YYYY-MM-DD. Ràng buộc: to_date ≥ from_date, khoảng tra cứu tối đa 30 ngày, to_date không lớn hơn ngày hiện tại. |
Ví dụ Request
{
"request_id": "MERCHANT1234BK202606050004",
"request_time": "2026-06-05 10:16:30",
"merchant_code": "MERCHANT1234",
"currency": "USD",
"from_date": "2026-06-01",
"to_date": "2026-06-04"
}
Response
| Tham số | Loại dữ liệu | Bắt buộc | Mô tả |
|---|---|---|---|
| response_code | int(4) | Có | Mã kết quả |
| response_message | string(200) | Có | Mô tả mã kết quả |
| merchant_code | string(20) | Có | Mã merchant |
| currency_pair | string(10) | Có | Cặp tiền tệ chuẩn hóa, ví dụ USD/VND |
| data | Array of Objects | Có | Danh sách tỷ giá theo ngày, sắp xếp tăng dần. Ngày không có dữ liệu không xuất hiện trong danh sách. |
Cấu trúc mảng data
| Tham số | Loại dữ liệu | Mô tả |
|---|---|---|
| date | string(10) | Ngày của tỷ giá, định dạng YYYY-MM-DD |
| sell_rate | decimal(18,2) | Tỷ giá chốt cuối ngày áp dụng cho chiều SELL (Merchant bán ngoại tệ, thu VND) |
| buy_rate | decimal(18,2) | Tỷ giá chốt cuối ngày áp dụng cho chiều BUY (Merchant dùng VND mua ngoại tệ) |
Ví dụ Response
{
"response_code": 200,
"response_message": "Success",
"merchant_code": "MERCHANT1234",
"currency_pair": "USD/VND",
"data": [
{ "date": "2026-06-01", "sell_rate": 26430.00, "buy_rate": 26495.00 },
{ "date": "2026-06-02", "sell_rate": 26440.00, "buy_rate": 26500.00 },
{ "date": "2026-06-03", "sell_rate": 26445.00, "buy_rate": 26505.00 },
{ "date": "2026-06-04", "sell_rate": 26450.00, "buy_rate": 26510.00 }
]
}
Mã lỗi
| Mã Response | Thông báo Response | Mô tả |
|---|---|---|
| 200 | Success | |
| 101 | System Error | Lỗi không mong muốn phía Baokim |
| 110 | Merchant code invalid | merchant_code không xác định |
| 120 | Invalid signature | Header Signature không hợp lệ |
| 404 | Currency not supported | Ngoại tệ yêu cầu không nằm trong danh mục Merchant |
| 416 | Invalid date range | to_date < from_date, khoảng > 30 ngày, hoặc to_date > ngày hiện tại |
| 422 | Validation Error | Trường request thiếu hoặc không hợp lệ |
| 429 | Too many requests | Vượt quá giới hạn tỷ lệ cho Merchant |